<!DOCTYPE html>
<html id="docs" lang="en" class="">
	<head>
	<meta charset="utf-8">
<title>ReplicationController - Kubernetes</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="shortcut icon" type="image/png" href="../../../images/favicon.png">
<link rel="stylesheet" type="text/css" href="../../../css/base_fonts.css">
<link rel="stylesheet" type="text/css" href="../../../css/styles.css">
<link rel="stylesheet" type="text/css" href="https://code.jquery.com/ui/1.12.1/themes/smoothness/jquery-ui.css">
<link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/sweetalert/1.1.3/sweetalert.min.css">
<link rel="stylesheet" type="text/css" href="../../../css/callouts.css">
<link rel="stylesheet" type="text/css" href="../../../css/custom-jekyll/tags.css">




<meta name="description" content="ReplicationController" />
<meta property="og:description" content="ReplicationController" />

<meta property="og:url" content="https://kubernetes.io/docs/concepts/workloads/controllers/replicationcontroller/" />
<meta property="og:title" content="ReplicationController - Kubernetes" />

<script
src="https://code.jquery.com/jquery-3.2.1.min.js"
integrity="sha256-hwg4gsxgFZhOsEEamdOYGBf13FyQuiTwlAQgxVSNgt4="
crossorigin="anonymous"></script>
<script
src="https://code.jquery.com/ui/1.12.1/jquery-ui.min.js"
integrity="sha256-VazP97ZCwtekAsvgPBSUwPFKdrwD3unUfSGVYrahUqU="
crossorigin="anonymous"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/sweetalert/1.1.3/sweetalert.min.js"></script>
<script src="../../../js/script.js"></script>
<script src="../../../js/custom-jekyll/tags.js"></script>


	</head>
	<body>
		<div id="cellophane" onclick="kub.toggleMenu()"></div>

<header>
    <a href="../../../index.html" class="logo"></a>

    <div class="nav-buttons" data-auto-burger="primary">
        <ul class="global-nav">
            
            
            <li><a href="../../home.1">Documentation</a></li>
            
            <li><a href="../../../blog/index.html">Blog</a></li>
            
            <li><a href="../../../partners/index.html">Partners</a></li>
            
            <li><a href="../../../community/index.html">Community</a></li>
            
            <li><a href="../../../case-studies/index.html">Case Studies</a></li>
            
            
             <li>
                <a href="index.html#">
                    English <span class="ui-icon ui-icon-carat-1-s"></span>
                </a>
                <ul>
                
                    <li><a href="../../../zh/index.html">中文 Chinese</a></li>
                
                    <li><a href="../../../ko/index.html">한국어 Korean</a></li>
                
                </ul>
            </li>
         
            <li>
                <a href="index.html#">
                    v1.11 <span class="ui-icon ui-icon-carat-1-s"></span>
                </a>
                <ul>
                
                    <li><a href="https://kubernetes.io">v1.12</a></li>
                
                    <li><a href="../../../index.html">v1.11</a></li>
                
                    <li><a href="https://v1-10.docs.kubernetes.io">v1.10</a></li>
                
                    <li><a href="https://v1-9.docs.kubernetes.io">v1.9</a></li>
                
                </ul>
            </li>
        </ul>
        
        <a href="../../tutorials/kubernetes-basics/index.html" class="button" id="tryKubernetes" data-auto-burger-exclude>Try Kubernetes</a>
        <button id="hamburger" onclick="kub.toggleMenu()" data-auto-burger-exclude><div></div></button>
    </div>

    <nav id="mainNav">
        <main data-auto-burger="primary">
        <div class="nav-box">
            <h3><a href="../../tutorials/stateless-application/hello-minikube/index.html">Get Started</a></h3>
            <p>Ready to get your hands dirty? Build a simple Kubernetes cluster that runs "Hello World" for Node.js.</p>
        </div>
        <div class="nav-box">
            <h3><a href="../../home.1">Documentation</a></h3>
            <p>Learn how to use Kubernetes with the use of walkthroughs, samples, and reference documentation. You can even <a href="../../../editdocs/index.html" data-auto-burger-exclude>help contribute to the docs</a>!</p>
        </div>
        <div class="nav-box">
            <h3><a href="../../../community/index.html">Community</a></h3>
            <p>If you need help, you can connect with other Kubernetes users and the Kubernetes authors, attend community events, and watch video presentations from around the web.</p>
        </div>
        <div class="nav-box">
            <h3><a href="../../../blog/index.html">Blog</a></h3>
            <p>Read the latest news for Kubernetes and the containers space in general, and get technical how-tos hot off the presses.</p>
        </div>
        </main>
        <main data-auto-burger="primary">
        <div class="left">
            <h5 class="github-invite">Interested in hacking on the core Kubernetes code base?</h5>
            <a href="https://github.com/kubernetes/kubernetes" class="button" data-auto-burger-exclude>View On Github</a>
        </div>

        <div class="right">
            <h5 class="github-invite">Explore the community</h5>
            <div class="social">
                <a href="https://twitter.com/kubernetesio" class="twitter"><span>Twitter</span></a>
                <a href="https://github.com/kubernetes/kubernetes" class="github"><span>Github</span></a>
                <a href="http://slack.k8s.io/" class="slack"><span>Slack</span></a>
                <a href="http://stackoverflow.com/questions/tagged/kubernetes" class="stack-overflow"><span>Stack Overflow</span></a>
                <a href="https://discuss.kubernetes.io" class="mailing-list"><span>Forum</span></a>
                <a href="https://calendar.google.com/calendar/embed?src=nt2tcnbtbied3l6gi2h29slvc0%40group.calendar.google.com" class="calendar"><span>Events Calendar</span></a>
            </div>
        </div>
        <div class="clear" style="clear: both"></div>
        </main>
    </nav>
</header>

		
		
		<section id="hero" class="light-text no-sub">
			









<h1>Concepts</h1>
<h5></h5>








<div id="vendorStrip" class="light-text">
	<ul>
		
		
		<li><a href="../../home.1">DOCUMENTATION</a></li>
		
		
		<li><a href="../../setup/index.html">SETUP</a></li>
		
		
		<li><a href="../../concepts/index.html" class="YAH">CONCEPTS</a></li>
		
		
		<li><a href="../../tasks/index.html">TASKS</a></li>
		
		
		<li><a href="../../tutorials/index.html">TUTORIALS</a></li>
		
		
		<li><a href="../../reference.1">REFERENCE</a></li>
		
	</ul>
	<div id="searchBox">
		<input type="text" id="search" placeholder="Search" onkeydown="if (event.keyCode==13) window.location.replace('/docs/search/?q=' + this.value)" autofocus="autofocus">
	</div>
</div>

		</section>
		
		
<section id="deprecationWarning">
  <main>
    <div class="content deprecation-warning">
      <h3>
        Documentation for Kubernetes v1.11 is no longer actively maintained. The version you are currently viewing is a static snapshot.
        For up-to-date documentation, see the <a href="https://kubernetes.io/docs/home/">latest</a> version.
      </h3>
    </div>
  </main>
</section>


		<section id="encyclopedia">
			
<div id="docsToc">
     <div class="pi-accordion">
    	
        
        
        
        
        
         
             
                 
             
         
             
                 
             
         
             
                 
                          
                          
                 
             
         
             
         
             
         
             
         
             
         
             
         
         
        
        <a class="item" data-title="Concepts" href="../../concepts/index.html"></a>

	
	
		
		
	<div class="item" data-title="Overview">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="What is Kubernetes?" href="../../concepts/overview/index.html"></a>

		
	
		
		
<a class="item" data-title="Kubernetes Components" href="../../concepts/overview/components.1"></a>

		
	
		
		
<a class="item" data-title="The Kubernetes API" href="../../concepts/overview/kubernetes-api/index.html"></a>

		
	
		
		
	<div class="item" data-title="Working with Kubernetes Objects">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Understanding Kubernetes Objects" href="../../concepts/overview/working-with-objects/kubernetes-objects.1"></a>

		
	
		
		
<a class="item" data-title="Names" href="../identifiers"></a>

		
	
		
		
<a class="item" data-title="Namespaces" href="../../concepts/overview/working-with-objects/namespaces.1"></a>

		
	
		
		
<a class="item" data-title="Labels and Selectors" href="../labels"></a>

		
	
		
		
<a class="item" data-title="Annotations" href="../../concepts/overview/working-with-objects/annotations.1"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Object Management Using kubectl">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Kubernetes Object Management" href="../../tutorials/object-management-kubectl/object-management/index.html"></a>

		
	
		
		
<a class="item" data-title="Managing Kubernetes Objects Using Imperative Commands" href="../../tutorials/object-management-kubectl/imperative-object-management-command/index.html"></a>

		
	
		
		
<a class="item" data-title="Imperative Management of Kubernetes Objects Using Configuration Files" href="../../tutorials/object-management-kubectl/imperative-object-management-configuration/index.html"></a>

		
	
		
		
<a class="item" data-title="Declarative Management of Kubernetes Objects Using Configuration Files" href="../../tutorials/object-management-kubectl/declarative-object-management-configuration/index.html"></a>

		
	

		</div>
	</div>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Compute, Storage, and Networking Extensions">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Cluster Administration Overview" href="../../concepts/cluster-administration/cluster-administration-overview/index.html"></a>

		
	
		
		
<a class="item" data-title="Certificates" href="../../concepts/cluster-administration/certificates/index.html"></a>

		
	
		
		
<a class="item" data-title="Cloud Providers" href="../../concepts/cluster-administration/cloud-providers/index.html"></a>

		
	
		
		
<a class="item" data-title="Managing Resources" href="../../concepts/cluster-administration/manage-deployment/index.html"></a>

		
	
		
		
<a class="item" data-title="Cluster Networking" href="../../admin/networking"></a>

		
	
		
		
<a class="item" data-title="Logging Architecture" href="../../concepts/cluster-administration/logging.1"></a>

		
	
		
		
<a class="item" data-title="Configuring kubelet Garbage Collection" href="../../concepts/cluster-administration/kubelet-garbage-collection/index.html"></a>

		
	
		
		
<a class="item" data-title="Federation" href="../../concepts/cluster-administration/federation/index.html"></a>

		
	
		
		
<a class="item" data-title="Proxies in Kubernetes" href="../../concepts/cluster-administration/proxies/index.html"></a>

		
	
		
		
<a class="item" data-title="Controller manager metrics" href="../../concepts/cluster-administration/controller-metrics/index.html"></a>

		
	
		
		
<a class="item" data-title="Installing Addons" href="../../concepts/cluster-administration/addons/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Kubernetes Architecture">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Nodes" href="../../admin/node.1"></a>

		
	
		
		
<a class="item" data-title="Master-Node communication" href="../../concepts/architecture/master-node-communication/index.html"></a>

		
	
		
		
<a class="item" data-title="Concepts Underlying the Cloud Controller Manager" href="../../concepts/architecture/cloud-controller/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Extending Kubernetes">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Extending your Kubernetes Cluster" href="../../concepts/overview/extending/index.html"></a>

		
	
		
		
	<div class="item" data-title="Extending the Kubernetes API">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Extending the Kubernetes API with the aggregation layer" href="../../concepts/api-extension/apiserver-aggregation.1"></a>

		
	
		
		
<a class="item" data-title="Custom Resources" href="../../concepts/api-extension/custom-resources/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Compute, Storage, and Networking Extensions">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Network Plugins" href="../../admin/network-plugins/index.html"></a>

		
	
		
		
<a class="item" data-title="Device Plugins" href="../../concepts/cluster-administration/device-plugins.1"></a>

		
	

		</div>
	</div>

		
	
		
		
<a class="item" data-title="Service Catalog" href="../../concepts/service-catalog/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Containers">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Images" href="../../concepts/containers/images/index.html"></a>

		
	
		
		
<a class="item" data-title="Container Environment Variables" href="../../concepts/containers/container-environment-variables/index.html"></a>

		
	
		
		
<a class="item" data-title="Container Lifecycle Hooks" href="../../concepts/containers/container-lifecycle-hooks/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Workloads">
		<div class="container">
		
		
	
	
		
		
	<div class="item" data-title="Pods">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Pod Overview" href="../../concepts/workloads/pods/pod-overview/index.html"></a>

		
	
		
		
<a class="item" data-title="Pods" href="../pods/index.html"></a>

		
	
		
		
<a class="item" data-title="Pod Lifecycle" href="../pod-states/index.html"></a>

		
	
		
		
<a class="item" data-title="Init Containers" href="../../concepts/abstractions/init-containers/index.html"></a>

		
	
		
		
<a class="item" data-title="Pod Preset" href="../../concepts/workloads/pods/podpreset/index.html"></a>

		
	
		
		
<a class="item" data-title="Disruptions" href="../../concepts/workloads/pods/disruptions/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Controllers">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="ReplicaSet" href="../../concepts/workloads/controllers/replicaset/index.html"></a>

		
	
		
		
<a class="item" data-title="ReplicationController" href="index.html"></a>

		
	
		
		
<a class="item" data-title="Deployments" href="../../concepts/workloads/controllers/deployment/index.html"></a>

		
	
		
		
<a class="item" data-title="StatefulSets" href="../../concepts/workloads/controllers/statefulset.md"></a>

		
	
		
		
<a class="item" data-title="DaemonSet" href="../../concepts/workloads/controllers/daemonset.1"></a>

		
	
		
		
<a class="item" data-title="Garbage Collection" href="../../concepts/workloads/controllers/garbage-collection/index.html"></a>

		
	
		
		
<a class="item" data-title="Jobs - Run to Completion" href="../../concepts/workloads/controllers/jobs-run-to-completion.1"></a>

		
	
		
		
<a class="item" data-title="CronJob" href="../../concepts/workloads/controllers/cron-jobs.1"></a>

		
	

		</div>
	</div>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Configuration">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Configuration Best Practices" href="../../concepts/configuration/overview/index.html"></a>

		
	
		
		
<a class="item" data-title="Managing Compute Resources for Containers" href="../compute-resources/index.html"></a>

		
	
		
		
<a class="item" data-title="Assigning Pods to Nodes" href="../node-selection/index.html"></a>

		
	
		
		
<a class="item" data-title="Taints and Tolerations" href="../../concepts/configuration/taint-and-toleration.1"></a>

		
	
		
		
<a class="item" data-title="Secrets" href="../secrets.1"></a>

		
	
		
		
<a class="item" data-title="Organizing Cluster Access Using kubeconfig Files" href="../../concepts/configuration/organize-cluster-access-kubeconfig/index.html"></a>

		
	
		
		
<a class="item" data-title="Pod Priority and Preemption" href="../../concepts/configuration/pod-priority-preemption/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Services, Load Balancing, and Networking">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Services" href="../services"></a>

		
	
		
		
<a class="item" data-title="DNS for Services and Pods" href="../../concepts/services-networking/dns-pod-service/index.html"></a>

		
	
		
		
<a class="item" data-title="Connecting Applications with Services" href="../../concepts/services-networking/connect-applications-service.1"></a>

		
	
		
		
<a class="item" data-title="Ingress" href="../../concepts/services-networking/ingress/index.html"></a>

		
	
		
		
<a class="item" data-title="Network Policies" href="../../concepts/services-networking/networkpolicies/index.html"></a>

		
	
		
		
<a class="item" data-title="Adding entries to Pod /etc/hosts with HostAliases" href="../../concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Storage">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Volumes" href="../../concepts/storage/volumes.1"></a>

		
	
		
		
<a class="item" data-title="Persistent Volumes" href="../persistent-volumes/index.html"></a>

		
	
		
		
<a class="item" data-title="Storage Classes" href="../../concepts/storage/storage-classes.1"></a>

		
	
		
		
<a class="item" data-title="Dynamic Volume Provisioning" href="../../concepts/storage/dynamic-provisioning/index.html"></a>

		
	
		
		
<a class="item" data-title="Node-specific Volume Limits" href="../../concepts/storage/storage-limits/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Policies">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Resource Quotas" href="../../concepts/policy/resource-quotas/index.html"></a>

		
	
		
		
<a class="item" data-title="Pod Security Policies" href="../pod-security-policy"></a>

		
	

		</div>
	</div>

		
	






     </div> 
    <button class="push-menu-close-button" onclick="kub.toggleToc()"></button>
</div> 

			<div id="docsContent">
				
<p><a href="../../editdocs#docs/concepts/workloads/controllers/replicationcontroller.md" id="editPageButton">Edit This Page</a></p>

<h1>ReplicationController</h1>



<blockquote class="note">
  <div><strong>NOTE:</strong> A <a href="../../concepts/workloads/controllers/deployment/index.html"><code>Deployment</code></a> that configures a <a href="../../concepts/workloads/controllers/replicaset/index.html"><code>ReplicaSet</code></a> is now the recommended way to set up replication.</div>
</blockquote>

<p>A <em>ReplicationController</em> ensures that a specified number of pod replicas are running at any one
time. In other words, a ReplicationController makes sure that a pod or a homogeneous set of pods is
always up and available.</p>









<ul id="markdown-toc">










<li><a href="index.html#how-a-replicationcontroller-works">How a ReplicationController Works</a></li>




<li><a href="index.html#running-an-example-replicationcontroller">Running an example ReplicationController</a></li>




<li><a href="index.html#writing-a-replicationcontroller-spec">Writing a ReplicationController Spec</a></li>




<li><a href="index.html#working-with-replicationcontrollers">Working with ReplicationControllers</a></li>




<li><a href="index.html#common-usage-patterns">Common usage patterns</a></li>




<li><a href="index.html#writing-programs-for-replication">Writing programs for Replication</a></li>




<li><a href="index.html#responsibilities-of-the-replicationcontroller">Responsibilities of the ReplicationController</a></li>




<li><a href="index.html#api-object">API Object</a></li>




<li><a href="index.html#alternatives-to-replicationcontroller">Alternatives to ReplicationController</a></li>




<li><a href="index.html#for-more-information">For more information</a></li>



















</ul>


<h2 id="how-a-replicationcontroller-works">How a ReplicationController Works</h2>

<p>If there are too many pods, the ReplicationController terminates the extra pods. If there are too few, the
ReplicationController starts more pods. Unlike manually created pods, the pods maintained by a
ReplicationController are automatically replaced if they fail, are deleted, or are terminated.
For example, your pods are re-created on a node after disruptive maintenance such as a kernel upgrade.
For this reason, you should use a ReplicationController even if your application requires
only a single pod. A ReplicationController is similar to a process supervisor,
but instead of supervising individual processes on a single node, the ReplicationController supervises multiple pods
across multiple nodes.</p>

<p>ReplicationController is often abbreviated to &ldquo;rc&rdquo; or &ldquo;rcs&rdquo; in discussion, and as a shortcut in
kubectl commands.</p>

<p>A simple case is to create one ReplicationController object to reliably run one instance of
a Pod indefinitely.  A more complex use case is to run several identical replicas of a replicated
service, such as web servers.</p>

<h2 id="running-an-example-replicationcontroller">Running an example ReplicationController</h2>

<p>This example ReplicationController config runs three copies of the nginx web server.</p>

<table class="includecode" id="replication-yaml">
    <thead>
        <tr>
            <th>
                <a href="https://github.com/kubernetes/website/blob/master/content/en/docs/concepts/workloads/controllers/replication.yaml" download="replication.yaml">
                    <code>replication.yaml docs/concepts/workloads/controllers</code>
                </a>
                <img src="../../../images/copycode.svg" style="max-height:24px" onclick="copyCode('replication-yaml')" title="Copy replication.yaml to clipboard">
            </th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-yaml" data-lang="yaml">apiVersion:<span style="color:#bbb"> </span>v1<span style="color:#bbb">
</span><span style="color:#bbb"></span>kind:<span style="color:#bbb"> </span>ReplicationController<span style="color:#bbb">
</span><span style="color:#bbb"></span>metadata:<span style="color:#bbb">
</span><span style="color:#bbb">  </span>name:<span style="color:#bbb"> </span>nginx<span style="color:#bbb">
</span><span style="color:#bbb"></span>spec:<span style="color:#bbb">
</span><span style="color:#bbb">  </span>replicas:<span style="color:#bbb"> </span><span style="color:#666">3</span><span style="color:#bbb">
</span><span style="color:#bbb">  </span>selector:<span style="color:#bbb">
</span><span style="color:#bbb">    </span>app:<span style="color:#bbb"> </span>nginx<span style="color:#bbb">
</span><span style="color:#bbb">  </span>template:<span style="color:#bbb">
</span><span style="color:#bbb">    </span>metadata:<span style="color:#bbb">
</span><span style="color:#bbb">      </span>name:<span style="color:#bbb"> </span>nginx<span style="color:#bbb">
</span><span style="color:#bbb">      </span>labels:<span style="color:#bbb">
</span><span style="color:#bbb">        </span>app:<span style="color:#bbb"> </span>nginx<span style="color:#bbb">
</span><span style="color:#bbb">    </span>spec:<span style="color:#bbb">
</span><span style="color:#bbb">      </span>containers:<span style="color:#bbb">
</span><span style="color:#bbb">      </span>-<span style="color:#bbb"> </span>name:<span style="color:#bbb"> </span>nginx<span style="color:#bbb">
</span><span style="color:#bbb">        </span>image:<span style="color:#bbb"> </span>nginx<span style="color:#bbb">
</span><span style="color:#bbb">        </span>ports:<span style="color:#bbb">
</span><span style="color:#bbb">        </span>-<span style="color:#bbb"> </span>containerPort:<span style="color:#bbb"> </span><span style="color:#666">80</span><span style="color:#bbb">
</span><span style="color:#bbb"></span></code></pre></div>  </td>
        </tr>
    </tbody>
</table>

<p>Run the example job by downloading the example file and then running this command:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">$ kubectl create -f ./replication.yaml
replicationcontroller <span style="color:#b44">&#34;nginx&#34;</span> created</code></pre></div>
<p>Check on the status of the ReplicationController using this command:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">$ kubectl describe replicationcontrollers/nginx
Name:        nginx
Namespace:   default
Selector:    <span style="color:#b8860b">app</span><span style="color:#666">=</span>nginx
Labels:      <span style="color:#b8860b">app</span><span style="color:#666">=</span>nginx
Annotations:    &lt;none&gt;
Replicas:    <span style="color:#666">3</span> current / <span style="color:#666">3</span> desired
Pods Status: <span style="color:#666">0</span> Running / <span style="color:#666">3</span> Waiting / <span style="color:#666">0</span> Succeeded / <span style="color:#666">0</span> Failed
Pod Template:
  Labels:       <span style="color:#b8860b">app</span><span style="color:#666">=</span>nginx
  Containers:
   nginx:
    Image:              nginx
    Port:               <span style="color:#666">80</span>/TCP
    Environment:        &lt;none&gt;
    Mounts:             &lt;none&gt;
  Volumes:              &lt;none&gt;
Events:
  FirstSeen       LastSeen     Count    From                        SubobjectPath    Type      Reason              Message
  ---------       --------     -----    ----                        -------------    ----      ------              -------
  20s             20s          <span style="color:#666">1</span>        <span style="color:#666">{</span>replication-controller <span style="color:#666">}</span>                    Normal    SuccessfulCreate    Created pod: nginx-qrm3m
  20s             20s          <span style="color:#666">1</span>        <span style="color:#666">{</span>replication-controller <span style="color:#666">}</span>                    Normal    SuccessfulCreate    Created pod: nginx-3ntk0
  20s             20s          <span style="color:#666">1</span>        <span style="color:#666">{</span>replication-controller <span style="color:#666">}</span>                    Normal    SuccessfulCreate    Created pod: nginx-4ok8v</code></pre></div>
<p>Here, three pods are created, but none is running yet, perhaps because the image is being pulled.
A little later, the same command may show:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">Pods Status:    <span style="color:#666">3</span> Running / <span style="color:#666">0</span> Waiting / <span style="color:#666">0</span> Succeeded / <span style="color:#666">0</span> Failed</code></pre></div>
<p>To list all the pods that belong to the ReplicationController in a machine readable form, you can use a command like this:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">$ <span style="color:#b8860b">pods</span><span style="color:#666">=</span><span style="color:#a2f;font-weight:bold">$(</span>kubectl get pods --selector<span style="color:#666">=</span><span style="color:#b8860b">app</span><span style="color:#666">=</span>nginx --output<span style="color:#666">=</span><span style="color:#b8860b">jsonpath</span><span style="color:#666">={</span>.items..metadata.name<span style="color:#666">}</span><span style="color:#a2f;font-weight:bold">)</span>
<span style="color:#a2f">echo</span> <span style="color:#b8860b">$pods</span>
nginx-3ntk0 nginx-4ok8v nginx-qrm3m</code></pre></div>
<p>Here, the selector is the same as the selector for the ReplicationController (seen in the
<code>kubectl describe</code> output, and in a different form in <code>replication.yaml</code>.  The <code>--output=jsonpath</code> option
specifies an expression that just gets the name from each pod in the returned list.</p>

<h2 id="writing-a-replicationcontroller-spec">Writing a ReplicationController Spec</h2>

<p>As with all other Kubernetes config, a ReplicationController needs <code>apiVersion</code>, <code>kind</code>, and <code>metadata</code> fields.
For general information about working with config files, see <a href="../../tutorials/object-management-kubectl/object-management/index.html">object management </a>.</p>

<p>A ReplicationController also needs a <a href="https://git.k8s.io/community/contributors/devel/api-conventions.md#spec-and-status" target="_blank"><code>.spec</code> section</a>.</p>

<h3 id="pod-template">Pod Template</h3>

<p>The <code>.spec.template</code> is the only required field of the <code>.spec</code>.</p>

<p>The <code>.spec.template</code> is a <a href="../../concepts/workloads/pods/pod-overview/index.html#pod-templates">pod template</a>. It has exactly the same schema as a <a href="../pods/index.html">pod</a>, except it is nested and does not have an <code>apiVersion</code> or <code>kind</code>.</p>

<p>In addition to required fields for a Pod, a pod template in a ReplicationController must specify appropriate
labels and an appropriate restart policy. For labels, make sure not to overlap with other controllers. See <a href="index.html#pod-selector">pod selector</a>.</p>

<p>Only a <a href="../pod-states/index.html#restart-policy"><code>.spec.template.spec.restartPolicy</code></a> equal to <code>Always</code> is allowed, which is the default if not specified.</p>

<p>For local container restarts, ReplicationControllers delegate to an agent on the node,
for example the <a href="../../admin/kubelet/index.html">Kubelet</a> or Docker.</p>

<h3 id="labels-on-the-replicationcontroller">Labels on the ReplicationController</h3>

<p>The ReplicationController can itself have labels (<code>.metadata.labels</code>).  Typically, you
would set these the same as the <code>.spec.template.metadata.labels</code>; if <code>.metadata.labels</code> is not specified
then it defaults to  <code>.spec.template.metadata.labels</code>.  However, they are allowed to be
different, and the <code>.metadata.labels</code> do not affect the behavior of the ReplicationController.</p>

<h3 id="pod-selector">Pod Selector</h3>

<p>The <code>.spec.selector</code> field is a <a href="../labels#label-selectors">label selector</a>. A ReplicationController
manages all the pods with labels that match the selector. It does not distinguish
between pods that it created or deleted and pods that another person or process created or
deleted. This allows the ReplicationController to be replaced without affecting the running pods.</p>

<p>If specified, the <code>.spec.template.metadata.labels</code> must be equal to the <code>.spec.selector</code>, or it will
be rejected by the API.  If <code>.spec.selector</code> is unspecified, it will be defaulted to
<code>.spec.template.metadata.labels</code>.</p>

<p>Also you should not normally create any pods whose labels match this selector, either directly, with
another ReplicationController, or with another controller such as Job. If you do so, the
ReplicationController thinks that it created the other pods.  Kubernetes does not stop you
from doing this.</p>

<p>If you do end up with multiple controllers that have overlapping selectors, you
will have to manage the deletion yourself (see <a href="index.html#working-with-replicationcontrollers">below</a>).</p>

<h3 id="multiple-replicas">Multiple Replicas</h3>

<p>You can specify how many pods should run concurrently by setting <code>.spec.replicas</code> to the number
of pods you would like to have running concurrently.  The number running at any time may be higher
or lower, such as if the replicas were just increased or decreased, or if a pod is gracefully
shutdown, and a replacement starts early.</p>

<p>If you do not specify <code>.spec.replicas</code>, then it defaults to 1.</p>

<h2 id="working-with-replicationcontrollers">Working with ReplicationControllers</h2>

<h3 id="deleting-a-replicationcontroller-and-its-pods">Deleting a ReplicationController and its Pods</h3>

<p>To delete a ReplicationController and all its pods, use <a href="../../reference/generated/kubectl/kubectl/index.html#delete"><code>kubectl
delete</code></a>.  Kubectl will scale the ReplicationController to zero and wait
for it to delete each pod before deleting the ReplicationController itself.  If this kubectl
command is interrupted, it can be restarted.</p>

<p>When using the REST API or go client library, you need to do the steps explicitly (scale replicas to
0, wait for pod deletions, then delete the ReplicationController).</p>

<h3 id="deleting-just-a-replicationcontroller">Deleting just a ReplicationController</h3>

<p>You can delete a ReplicationController without affecting any of its pods.</p>

<p>Using kubectl, specify the <code>--cascade=false</code> option to <a href="../../reference/generated/kubectl/kubectl/index.html#delete"><code>kubectl delete</code></a>.</p>

<p>When using the REST API or go client library, simply delete the ReplicationController object.</p>

<p>Once the original is deleted, you can create a new ReplicationController to replace it.  As long
as the old and new <code>.spec.selector</code> are the same, then the new one will adopt the old pods.
However, it will not make any effort to make existing pods match a new, different pod template.
To update pods to a new spec in a controlled way, use a <a href="index.html#rolling-updates">rolling update</a>.</p>

<h3 id="isolating-pods-from-a-replicationcontroller">Isolating pods from a ReplicationController</h3>

<p>Pods may be removed from a ReplicationController&rsquo;s target set by changing their labels. This technique may be used to remove pods from service for debugging, data recovery, etc. Pods that are removed in this way will be replaced automatically (assuming that the number of replicas is not also changed).</p>

<h2 id="common-usage-patterns">Common usage patterns</h2>

<h3 id="rescheduling">Rescheduling</h3>

<p>As mentioned above, whether you have 1 pod you want to keep running, or 1000, a ReplicationController will ensure that the specified number of pods exists, even in the event of node failure or pod termination (for example, due to an action by another control agent).</p>

<h3 id="scaling">Scaling</h3>

<p>The ReplicationController makes it easy to scale the number of replicas up or down, either manually or by an auto-scaling control agent, by simply updating the <code>replicas</code> field.</p>

<h3 id="rolling-updates">Rolling updates</h3>

<p>The ReplicationController is designed to facilitate rolling updates to a service by replacing pods one-by-one.</p>

<p>As explained in <a href="http://issue.k8s.io/1353" target="_blank">#1353</a>, the recommended approach is to create a new ReplicationController with 1 replica, scale the new (+1) and old (-1) controllers one by one, and then delete the old controller after it reaches 0 replicas. This predictably updates the set of pods regardless of unexpected failures.</p>

<p>Ideally, the rolling update controller would take application readiness into account, and would ensure that a sufficient number of pods were productively serving at any given time.</p>

<p>The two ReplicationControllers would need to create pods with at least one differentiating label, such as the image tag of the primary container of the pod, since it is typically image updates that motivate rolling updates.</p>

<p>Rolling update is implemented in the client tool
<a href="../../reference/generated/kubectl/kubectl/index.html#rolling-update"><code>kubectl rolling-update</code></a>. Visit <a href="../../tasks/run-application/rolling-update-replication-controller/index.html"><code>kubectl rolling-update</code> task</a> for more concrete examples.</p>

<h3 id="multiple-release-tracks">Multiple release tracks</h3>

<p>In addition to running multiple releases of an application while a rolling update is in progress, it&rsquo;s common to run multiple releases for an extended period of time, or even continuously, using multiple release tracks. The tracks would be differentiated by labels.</p>

<p>For instance, a service might target all pods with <code>tier in (frontend), environment in (prod)</code>.  Now say you have 10 replicated pods that make up this tier.  But you want to be able to &lsquo;canary&rsquo; a new version of this component.  You could set up a ReplicationController with <code>replicas</code> set to 9 for the bulk of the replicas, with labels <code>tier=frontend, environment=prod, track=stable</code>, and another ReplicationController with <code>replicas</code> set to 1 for the canary, with labels <code>tier=frontend, environment=prod, track=canary</code>.  Now the service is covering both the canary and non-canary pods.  But you can mess with the ReplicationControllers separately to test things out, monitor the results, etc.</p>

<h3 id="using-replicationcontrollers-with-services">Using ReplicationControllers with Services</h3>

<p>Multiple ReplicationControllers can sit behind a single service, so that, for example, some traffic
goes to the old version, and some goes to the new version.</p>

<p>A ReplicationController will never terminate on its own, but it isn&rsquo;t expected to be as long-lived as services. Services may be composed of pods controlled by multiple ReplicationControllers, and it is expected that many ReplicationControllers may be created and destroyed over the lifetime of a service (for instance, to perform an update of pods that run the service). Both services themselves and their clients should remain oblivious to the ReplicationControllers that maintain the pods of the services.</p>

<h2 id="writing-programs-for-replication">Writing programs for Replication</h2>

<p>Pods created by a ReplicationController are intended to be fungible and semantically identical, though their configurations may become heterogeneous over time. This is an obvious fit for replicated stateless servers, but ReplicationControllers can also be used to maintain availability of master-elected, sharded, and worker-pool applications. Such applications should use dynamic work assignment mechanisms, such as the <a href="https://www.rabbitmq.com/tutorials/tutorial-two-python.html" target="_blank">RabbitMQ work queues</a>, as opposed to static/one-time customization of the configuration of each pod, which is considered an anti-pattern. Any pod customization performed, such as vertical auto-sizing of resources (for example, cpu or memory), should be performed by another online controller process, not unlike the ReplicationController itself.</p>

<h2 id="responsibilities-of-the-replicationcontroller">Responsibilities of the ReplicationController</h2>

<p>The ReplicationController simply ensures that the desired number of pods matches its label selector and are operational. Currently, only terminated pods are excluded from its count. In the future, <a href="http://issue.k8s.io/620" target="_blank">readiness</a> and other information available from the system may be taken into account, we may add more controls over the replacement policy, and we plan to emit events that could be used by external clients to implement arbitrarily sophisticated replacement and/or scale-down policies.</p>

<p>The ReplicationController is forever constrained to this narrow responsibility. It itself will not perform readiness nor liveness probes. Rather than performing auto-scaling, it is intended to be controlled by an external auto-scaler (as discussed in <a href="http://issue.k8s.io/492" target="_blank">#492</a>), which would change its <code>replicas</code> field. We will not add scheduling policies (for example, <a href="http://issue.k8s.io/367#issuecomment-48428019" target="_blank">spreading</a>) to the ReplicationController. Nor should it verify that the pods controlled match the currently specified template, as that would obstruct auto-sizing and other automated processes. Similarly, completion deadlines, ordering dependencies, configuration expansion, and other features belong elsewhere. We even plan to factor out the mechanism for bulk pod creation (<a href="http://issue.k8s.io/170" target="_blank">#170</a>).</p>

<p>The ReplicationController is intended to be a composable building-block primitive. We expect higher-level APIs and/or tools to be built on top of it and other complementary primitives for user convenience in the future. The &ldquo;macro&rdquo; operations currently supported by kubectl (run, scale, rolling-update) are proof-of-concept examples of this. For instance, we could imagine something like <a href="http://techblog.netflix.com/2012/06/asgard-web-based-cloud-management-and.html" target="_blank">Asgard</a> managing ReplicationControllers, auto-scalers, services, scheduling policies, canaries, etc.</p>

<h2 id="api-object">API Object</h2>

<p>Replication controller is a top-level resource in the Kubernetes REST API. More details about the
API object can be found at:
<a href="../../reference/generated/kubernetes-api/v1.11/index.html#replicationcontroller-v1-core">ReplicationController API object</a>.</p>

<h2 id="alternatives-to-replicationcontroller">Alternatives to ReplicationController</h2>

<h3 id="replicaset">ReplicaSet</h3>

<p><a href="../../concepts/workloads/controllers/replicaset/index.html"><code>ReplicaSet</code></a> is the next-generation ReplicationController that supports the new <a href="../labels#set-based-requirement">set-based label selector</a>.
It’s mainly used by <a href="../../concepts/workloads/controllers/deployment/index.html"><code>Deployment</code></a> as a mechanism to orchestrate pod creation, deletion and updates.
Note that we recommend using Deployments instead of directly using Replica Sets, unless you require custom update orchestration or don’t require updates at all.</p>

<h3 id="deployment-recommended">Deployment (Recommended)</h3>

<p><a href="../../concepts/workloads/controllers/deployment/index.html"><code>Deployment</code></a> is a higher-level API object that updates its underlying Replica Sets and their Pods
in a similar fashion as <code>kubectl rolling-update</code>. Deployments are recommended if you want this rolling update functionality,
because unlike <code>kubectl rolling-update</code>, they are declarative, server-side, and have additional features.</p>

<h3 id="bare-pods">Bare Pods</h3>

<p>Unlike in the case where a user directly created pods, a ReplicationController replaces pods that are deleted or terminated for any reason, such as in the case of node failure or disruptive node maintenance, such as a kernel upgrade. For this reason, we recommend that you use a ReplicationController even if your application requires only a single pod. Think of it similarly to a process supervisor, only it supervises multiple pods across multiple nodes instead of individual processes on a single node.  A ReplicationController delegates local container restarts to some agent on the node (for example, Kubelet or Docker).</p>

<h3 id="job">Job</h3>

<p>Use a <a href="../../concepts/jobs/run-to-completion-finite-workloads/index.html"><code>Job</code></a> instead of a ReplicationController for pods that are expected to terminate on their own
(that is, batch jobs).</p>

<h3 id="daemonset">DaemonSet</h3>

<p>Use a <a href="../../concepts/workloads/controllers/daemonset.1"><code>DaemonSet</code></a> instead of a ReplicationController for pods that provide a
machine-level function, such as machine monitoring or machine logging.  These pods have a lifetime that is tied
to a machine lifetime: the pod needs to be running on the machine before other pods start, and are
safe to terminate when the machine is otherwise ready to be rebooted/shutdown.</p>

<h2 id="for-more-information">For more information</h2>

<p>Read <a href="../../tutorials/stateless-application/run-stateless-ap-replication-controller/index.html">Run Stateless AP Replication Controller</a>.</p>














				<div class="issue-button-container">
					<p><a href="index.html"><img src="https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/concepts/workloads/controllers/replicationcontroller.md?pixel" alt="Analytics" /></a></p>
					
					
					<script type="text/javascript">
					PDRTJS_settings_8345992 = {
					"id" : "8345992",
					"unique_id" : "\/docs\/concepts\/workloads\/controllers\/replicationcontroller\/",
					"title" : "ReplicationController",
					"permalink" : "https:\/\/kubernetes.io\/docs\/concepts\/workloads\/controllers\/replicationcontroller\/"
					};
					(function(d,c,j){if(!document.getElementById(j)){var pd=d.createElement(c),s;pd.id=j;pd.src=('https:'==document.location.protocol)?'https://polldaddy.com/js/rating/rating.js':'http://i0.poll.fm/js/rating/rating.js';s=document.getElementsByTagName(c)[0];s.parentNode.insertBefore(pd,s);}}(document,'script','pd-rating-js'));
					</script>
					<a href="index.html" onclick="window.open('https://github.com/kubernetes/website/issues/new?title=Issue%20with%20' +
					'k8s.io'+window.location.pathname)" class="button issue">Create an Issue</a>
					
					
					
					<a href="../../editdocs#docs/concepts/workloads/controllers/replicationcontroller.md" class="button issue">Edit this Page</a>
					
				</div>
			</div>
		</section>
		<footer>
    <main class="light-text">
        <nav>
            
            
            
            <a href="../../home.1">Documentation</a>
            
            <a href="../../../blog/index.html">Blog</a>
            
            <a href="../../../partners/index.html">Partners</a>
            
            <a href="../../../community/index.html">Community</a>
            
            <a href="../../../case-studies/index.html">Case Studies</a>
            
        </nav>
        <div class="social">
            <div>
                <a href="https://twitter.com/kubernetesio" class="twitter"><span>twitter</span></a>
                <a href="https://github.com/kubernetes/kubernetes" class="github"><span>Github</span></a>
                <a href="http://slack.k8s.io/" class="slack"><span>Slack</span></a>
            </div>
            <div>
                <a href="http://stackoverflow.com/questions/tagged/kubernetes" class="stack-overflow"><span>Stack Overflow</span></a>
                <a href="https://discuss.kubernetes.io" class="mailing-list"><span>Forum</span></a>
                <a href="https://calendar.google.com/calendar/embed?src=nt2tcnbtbied3l6gi2h29slvc0%40group.calendar.google.com" class="calendar"><span>Events Calendar</span></a>
            </div>
            <div>
                <a href="../../getting-started-guides/index.html" class="button">Get Kubernetes</a>
                <a href="https://git.k8s.io/community/contributors/guide" class="button">Contribute</a>
            </div>
        </div>
        <div id="miceType" class="center">
            &copy; 2018 The Kubernetes Authors | Documentation Distributed under <a href="https://git.k8s.io/website/LICENSE" class="light-text">CC BY 4.0</a>
        </div>
        <div id="miceType" class="center">
            Copyright &copy; 2018 The Linux Foundation&reg;. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our <a href="https://www.linuxfoundation.org/trademark-usage" class="light-text">Trademark Usage page</a>
        </div>
    </main>
</footer>

		<button class="flyout-button" onclick="kub.toggleToc()"></button>

<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
    (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-36037335-10', 'auto');
ga('send', 'pageview');


(function () {
    window.addEventListener('DOMContentLoaded', init)

        
        function init() {
            window.removeEventListener('DOMContentLoaded', init)
                hideNav()
        }

    function hideNav(toc){
        if (!toc) toc = document.querySelector('#docsToc')
        if (!toc) return
            var container = toc.querySelector('.container')

                
                if (container) {
                    if (container.childElementCount === 0 || toc.querySelectorAll('a.item').length === 1) {
                        toc.style.display = 'none'
                            document.getElementById('docsContent').style.width = '100%'
                    }
                } else {
                    requestAnimationFrame(function () {
                        hideNav(toc)
                    })
                }
    }
})();
</script>



	</body>
</html>